fix(mcp): validate_expression keeps the hidden __search companion out of scope - #33451

📓 Docs Drift Check

2 anchor(s) derived from 3 changed package(s); no hand-written page names any of them. ⚠️ 3 changed file(s) yielded no anchor (packages/mcp/vitest.config.ts, packages/spec/api-surface/data.json, packages/spec/export-origins/data.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin a70779241a49f88b758dc6a212e3ed0d7071d5c6 && git checkout a70779241a49f88b758dc6a212e3ed0d7071d5c6
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e40cd1e28dd79e60e7f4be0db06f071f3f962574 3c1cdfab46a834fff8cbbe27c931c78b2560dae2 && git checkout -B drift-repro e40cd1e28dd79e60e7f4be0db06f071f3f962574 && git merge --no-ff 3c1cdfab46a834fff8cbbe27c931c78b2560dae2

node scripts/docs-audit/affected-docs.mjs --json e40cd1e28dd79e60e7f4be0db06f071f3f962574

Contract-review-claim: session_016WV4cxDxAYxdtDhtR1kQQe · head 8fd1945 · 2026-11-14T21:33Z

review#2 (server area pilot, A4).

Review: PASS

Head: 8fd19455fb69d60ef3eb2a02cda85c590634bc7a · reviewer review#2 (session_016WV4cxDxAYxdtDhtR1kQQe) · area A4 · Fixes #33338

Checked:

• Right place. The inScope.fields list and the field set the validator judges against are both built in validate_expression (packages/mcp/src/mcp-http-tools.ts), not in runtime domains/mcp.ts as the card guessed. Skipping the companion there fixes the list and the verdict together. Pinned: inScope.fields keeps name, email and created_at and drops __search, and record.__search != '' is refused unknown-field at the validation, formula and flow_condition sites, matching what validateStackExpressions (the os validate gate) answers for the same rule.
• One name, not a second list (the card's constraint). The filter reads the engine's own SEARCH_COMPANION_FIELD instead of a literal, the same import plugin-pinyin-search already uses, and the fixture is stamped by the engine's own provisionSearchCompanion. Filtering on the stamped hidden: true would have been wrong, because an author field may be hidden in the UI and still be readable in expressions.
• Clause-②: no is accepted. An expression the gate already refused is now refused here too (aligning the advisory tool with the gate, the same shape as mcp: validate_expression still answers ok where the validation/formula gate refuses (null-guard, undeclared hop field, and the rest of the gate's private passes) #32872's validate_expression parity). inScope.fields loses a column no read ever served. No export moves.

On the dependency cost you asked about: acceptable.

• No cycle: @objectstack/objectql does not depend on @objectstack/mcp, nor does anything below it.
• Every in-repo consumer of @objectstack/mcp (cli, verify, the QA packages) already depends on @objectstack/objectql, and a host that serves MCP has already loaded the engine, so the lazy import() resolves to an already-loaded module there.

Nits (optional):

• N1: import from the lean entry @objectstack/objectql/core (ADR-0076), which re-exports SEARCH_COMPANION_FIELD and provisionSearchCompanion without pulling the barrel's @objectstack/metadata-protocol graph into a process that has not loaded it yet (a standalone stdio MCP). Adjust the vitest alias to match (../objectql/src/core.ts).
• N2: packages/mcp is outside the pilot's leased paths (server#7, epic [Epic] MCP: what an agent can read and write on the HTTP MCP door, and answers that agree with the gate #32897). Before arming, check that no open server#7 PR changes the validate_expression handler in mcp-http-tools.ts.

CI at review time: 11 success, 24 in progress, none failed. Landing needs all green.

Generated by Claude Code

Contract-review-claim: session_016WV4cxDxAYxdtDhtR1kQQe · head a182226 · 2026-11-14T23:12:52Z

Contract-review-claim: session_016WV4cxDxAYxdtDhtR1kQQe · head 3c1cdfa · 2026-11-14T23:14:56Z

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 3c1cdfab46a834fff8cbbe27c931c78b2560dae2
Local-runs: none
Scope: packages/spec/src/data/search-fields.ts + packages/objectql/src/search-companion.ts, packages/mcp/src/mcp-http-tools.ts, packages/spec/api-surface/data.json, packages/spec/export-origins/data.json

review#2 (server area pilot) · area A4 · Fixes #33338 · delta on my PASS at 8fd19455 (6884553156), via a182226e. The published-spec face is new in this delta, so this record replaces the earlier plain review.

① Derived judgments

• Why the delta exists. At 8fd19455 the tool imported the engine lazily for one constant. Test Core 7/8 timed out on the first validate_expression call, because loading the objectql barrel under the source alias took seconds. Moving the name to the spec removes the engine load from the tool's path entirely. That is a better fix than my N1 (/core), which only shortened it.
• packages/spec/src/data/search-fields.ts adds export const SEARCH_COMPANION_FIELD = '__search', a plain string constant with no schema and no parse behaviour. Its jsdoc matches what the code does: resolveSearchFields never returns it, the engine strips it on read, and the tool now leaves it out.
• packages/objectql/src/search-companion.ts imports the constant from @objectstack/spec/data and re-exports it under the same name. The value is identical ('__search'), so every engine caller and every stored column name is unchanged. The module's own uses read the same binding.
• packages/mcp/src/mcp-http-tools.ts imports the constant statically from @objectstack/spec/data, which mcp already depended on, and skips that one field name when building fields/fieldTypes. Every other field, injected system columns included, is listed as before. @objectstack/objectql is only a devDependency of mcp now, for the pin, so mcp gains no runtime dependency on the engine. That also resolves the dependency question from my first round.
• api-surface/data.json and export-origins/data.json each gain exactly the one entry, with its origin src/data/search-fields.ts.
• Tests:
  • The precondition proves that the served object really carries the companion; it is provisioned by the engine's own provisionSearchCompanion.
  • inScope.fields keeps name, email and created_at and drops the companion.
  • A read of the companion is refused unknown-field at all three sites, and os validate's validateStackExpressions refuses the same expression. That is the parity the card asks for.

② Semver level

• Clause-②: yes (widening) is right: there is a new root export on @objectstack/spec/data, the feat(lint): advise a template default that reads like a variable path, and a notify node missing a required template variable #33321/feat(lint): warn on a multi update_record that moves a stored expression input #33336 precedent.
• Metadata-protocol: none is right. A TypeScript constant adds no key, value or metadata type an author can write, and no authorable-surface baseline moves.
• Under AGENTS.md's level rule, none takes patch whatever the Clause-② arm, so the spec entry belongs at patch, as at this head. The minor at a182226e was refused by Check Changeset for that reason. mcp and objectql at patch are right.

③ Boundary flags

• Not security sensitive. The tool now discloses one fewer field name, and that name is platform plumbing.
• Cross-area: packages/spec/src/data/** and packages/objectql are outside A4's narrow surface, but the change is one additive constant and a same-value re-export.
• packages/mcp is not leased in the pilot (server#7), so it stays with A4 as before.

④ Design judgment

• Holds against the cited code. One name, owned by the protocol, read by both the engine and the tool, is the right layering: the tool needs to recognise the column, not to run the engine. Keeping objectql's export under the same name avoids a breaking move for engine callers. The alternative, a hard-coded '__search' in mcp, would be the second spelling that the earlier rounds were avoiding.
• Holds against the scenario. The card's scenario (record.__search != '' answering ok in the tool while os validate refuses it) is now refused at all three sites, and the companion is no longer listed.
• N1 (nit, not blocking): the spec jsdoc says "no expression may read it". The enforcement of that is the tool's skip plus the gate's declared-field universe, not anything in the spec. That is accurate as a statement of the rule, and noted only so that a later reader does not look for a spec-side refusal.

Implemented-by: claude/area-A4-33338
Reviewed-by: session_016WV4cxDxAYxdtDhtR1kQQe

VERDICT: PASS

CI on this head was still running at review time (1 success, 7 skipped, 20 in progress; the 1 cancelled run was superseded by the push). Land only once it is green; Test Core 7/8 is the one to watch.

domain:server#5 · os-elon-musk · session_016WV4cw787kMeaX7oyz7DDC

ACCEPT · area A4 · head 3c1cdfa · 2026-11-14T23:40Z

• review#2 contract record PASS at this head (comment 6885755104, CONTRACT_REVIEW_TIER, replaces the plain PASS 6884553156). Clause-② yes (widening), Metadata-protocol none, spec at patch.
• The Test Core 7/8 timeout on the first head (8fd1945) was this PR's own cost: an engine import on the first validate_expression call. It is removed at the root, and the case runs 60 ms locally. Test Core 1–8/8 are green at this head.
• check-governed-merges --pr 33451: NOT governed.
• All check-runs on this head completed green, except one PR-body guards run that a later run of the same guard superseded (cancelled; the later run is green).
• Landing under the maintainer's area go (pilot Dispatch by code area instead of by card: area leases, one PR per coupled set, follow-ups folded (pilot on domain:server after 18.4.0; maintainer launches) #33059): ready + auto-merge.

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 43664809991 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

分类：failure —— 按下面的日志分诊。

失败的 job（日志抽取，best effort）：

• Test Core (5/8) — 失败步骤: Run this shard's tests

  @objectstack/plugin-approvals:test:  FAIL  src/action-page-member.integration.test.ts > [#22578] handleActionPage — the ADR-0043 action page from a Request > GET renders the confirm page for a live to
    ↳ 失败原因: @objectstack/plugin-approvals:test: Error: Test timed out in 5000ms.
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

⚠️ 断言这一侧有一类例外，判据是断言在测什么，不是它是不是 AssertionError。 断言的对象是产品行为（一个值、一个形状、一次拒收）⇒ 照上面读：真实的行为改变，去查，⛔ 不要重排掉；
断言的对象是这次实验自身的有效性前提（跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件）⇒ 它跟超时是同一类，同样对负载敏感，重排一次是合法的判别手段。
识别是机械的：断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为（真回归）；
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提：它守护的那条不变式当时是绿的，同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量，仍然是时间测量。（⛔ 这只改「怎么读一次红」，不改「哪些测试可以重排」——后者由别处管。）

跨 PR 相同签名（24h，按失败测试文件聚合）：

• src/action-page-member.integration.test.ts — 24h 内已弹出 10 个 PR（feat(auth)!: a managed environment adds pending, SSO-only people, and ban works without the admin plugin #33227、fix(objectql, runtime)!: a function's bare-name read is refused naming both when the platform and a package hold the name, and answers nothing for a name only a disabled package holds (ADR-0150 D4) #33439、fix(lint)!: os build and the object_extension publish door refuse a formula cycle an object extension adds #33442、feat(plugin-security): a host can keep a platform baseline contribution at read, or decline it #33444、fix(plugin-webhooks, runtime): webhook remedies name the ?package= address, and a name refused whole answers 409 at every address #33450、fix(mcp): validate_expression keeps the hidden __search companion out of scope #33451、docs(plugin-hono-server, hono): say which 304 answers carry Vary, and that the hosted door leaves compression to the platform #33452、fix(objectql): the security-catalog name-conflict refusals say a permission set holds one name per namespace #33463、docs(ui): a contributed navigation entry's order sorts it among the target app's own entries #33472、docs(rest): name the 503 row and add the partial-judgement row in the released 2fc3fce CHANGELOG entry #33495），分属 5 条投机栈 ⇒ 5 次独立命中。汇总 issue：Queue-flake anchor: src/action-page-member.integration.test.ts #33508（已刷新）
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 23 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

domain:server#5 · os-elon-musk · session_016WV4cw787kMeaX7oyz7DDC

Queue ejection disposal · area A4 · head 3c1cdfa · 2026-11-15T02:10Z

• Ejecting build: 43664809991 (triage 6887744866). It failed in Test Core (5/8) on @objectstack/plugin-approvals src/action-page-member.integration.test.ts with "Test timed out in 5000ms".
• This PR does not touch plugin-approvals; its diff is spec/data, objectql search-companion and mcp. The failure is a timeout, not an assertion.
• It is a known signature. The ledger anchor is Queue-flake anchor: src/action-page-member.integration.test.ts #33508 (queue-flake-anchor), with 10 PRs ejected in 24h, and its fix is in flight as test(plugin-approvals): pay the translations load at module top so the action-page suite's first case stops timing out #33543.
• Branch taken: a known flaky signature on an unchanged head ⇒ re-queue once, as-is. If the same signature ejects it again, I stop and wait for test(plugin-approvals): pay the translations load at module top so the action-page suite's first case stops timing out #33543.

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 43666747033 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

分类：failure —— 按下面的日志分诊。

失败的 job（日志抽取，best effort）：

• Dogfood Regression Gate (1/3) — 失败步骤: Boot example apps and exercise real user flows

  @objectstack/dogfood:test:  FAIL   isolated  test/bare-name-one-holder-ai-family.dogfood.test.ts > agent, skill and tool names held per namespace, on a booted showcase > [#31985] a package-less tool r
    ↳ 失败原因: @objectstack/dogfood:test: Error: Test timed out in 5000ms.
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

⚠️ 断言这一侧有一类例外，判据是断言在测什么，不是它是不是 AssertionError。 断言的对象是产品行为（一个值、一个形状、一次拒收）⇒ 照上面读：真实的行为改变，去查，⛔ 不要重排掉；
断言的对象是这次实验自身的有效性前提（跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件）⇒ 它跟超时是同一类，同样对负载敏感，重排一次是合法的判别手段。
识别是机械的：断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为（真回归）；
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提：它守护的那条不变式当时是绿的，同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量，仍然是时间测量。（⛔ 这只改「怎么读一次红」，不改「哪些测试可以重排」——后者由别处管。）

跨 PR 相同签名（24h，按失败测试文件聚合）：

• test/bare-name-one-holder-ai-family.dogfood.test.ts — 24h 窗口内只有本 PR 撞到过，暂不汇总（再有一个不同 PR 撞到就会自动开汇总 issue）。
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• ⚠️ 本 PR 过去 24h 已在队列失败 1 次（不含本次）。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突，重排不解决。
• 过去 24h 队列共有 22 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

domain:server#5 · os-elon-musk · session_016WV4cw787kMeaX7oyz7DDC

Queue ejection #2 · area A4 · head 3c1cdfa · 2026-11-15T02:46Z

• Ejecting build: 43666747033 (triage 6888131608), Dogfood Regression Gate (1/3).
• Signature: test/bare-name-one-holder-ai-family.dogfood.test.ts › "agent, skill and tool names held per namespace, on a booted showcase" › "[objectql: narrow the phase-1 one-holder refusal from environment to namespace for tool (ADR-0150 child B, tool) #31985] a package-less tool r…", failing with "Test timed out in 5000ms".
• This is a NEW signature: no anchor issue yet, and only this PR has hit it in 24h. The first ejection (Queue-flake anchor: src/action-page-member.integration.test.ts #33508's approvals flake) was a different signature.
• Initial judgement: a timeout, not an assertion. This PR's diff is the SEARCH_COMPANION_FIELD constant in spec/data, objectql's re-export, and validate_expression's in-scope field list. It changes no tool, agent or skill naming or registration. But the dogfood boot imports the whole showcase, so the failing file's import closure is NOT disjoint from the diff. The three re-queue facts therefore do not all hold.
• Branch taken: no re-queue on my own judgement. I have asked the queue-duty reviewer to rule. Nothing is pushed to this PR in the meantime.

domain:server#5 · os-elon-musk · session_016WV4cw787kMeaX7oyz7DDC

Queue re-enqueue · area A4 · head 3c1cdfa · 2026-11-15T02:47Z

The queue-duty reviewer (review#1) ruled that ejection #2 (run 43666747033) is a FLAKE, a timing cliff:

• The timed-out case does 2 PUTs and 3 install-locals.
• The file's own control case measures one install-local at about 1.9 s on that runner, so three cost about 5.7 s against the 5000 ms budget.
• The other 26 cases in the file passed, and this diff is not on the install or tool-row path.

The budget fix is routed to the test's owner. Re-enqueued on the same head, with nothing pushed.